Node / ReticulumProjects / MeshChatX.git / files / docs / en / installation.md

Displaying Raw • View rendered • Download

Tc9d1d9# Installation and setup

MeshChatX can be installed in several ways. All release artifacts that ship the web UI include pre-built frontend assets. You do not need Node.js on the machine that only runs the Python wheel or Docker image.

Tc9d1d9## Requirements

| Component | Version |

| --------- | -------------------------------------------------- |

| Python | 3.11 or newer (Ta5d6ff`pyproject.toml`) |

| Node.js | 24 or newer (development and frontend builds only) |

| pnpm | 11.1.2 (development) |

| UV | Used by Taskfile and CI |

**Browsers for the web UI:** Safari 16.4+, Chrome 111+, Firefox 128+.

Tc9d1d9## Choose an install method

| Method | Frontend included | Best for |

| ---------------- | ----------------- | ---------------------------------------- |

| Docker image | Yes | Fast server setup on Linux |

| Python wheel | Yes | Headless install without building the UI |

| Linux AppImage | Yes | Portable desktop on x64 or arm64 |

| Debian Ta5d6ff`.deb` | Yes | Debian and Ubuntu systems |

| RPM package | Yes | Fedora, RHEL, openSUSE style systems |

| Electron desktop | Yes | Integrated desktop with bundled backend |

| Android APK | Yes | Phones, tablets, Meta Quest sideload |

| From source | Built locally | Development and custom builds |

Release images are published to Docker Hub (Ta5d6ff`quad4io/meshchatx`) and GHCR (Ta5d6ff`ghcr.io/quad4-software/meshchatx`). Tag suffixes: none for the standard Alpine image, Ta5d6ff`-hardened` for Chainguard/Wolfi, Ta5d6ff`-extra` for Alpine plus i2pd and yggdrasil (Ta5d6ff`VARIANT=extra` on the same Dockerfile).

Tc9d1d9## Docker

Quick start with Compose:

Ta5d6ff```Ta5d6ffbash

docker compose up -d

Ta5d6ff```

Manual run with a named volume for persistence:

Ta5d6ff```Ta5d6ffbash

docker run -d --name reticulum-meshchatx Tffea00\

--restart unless-stopped Tffea00\

--init Tffea00\

--user T79c0ff1000:1000 Tffea00\

--security-opt no-new-privileges:true Tffea00\

--cap-drop ALL Tffea00\

--read-only Tffea00\

--tmpfs /tmp:noexec,nosuid,sizeTff7b72=256m Tffea00\

--tmpfs /home/meshchat:nosuid,sizeTff7b72=64m Tffea00\

--cpusTff7b72=T79c0ff2.0 Tffea00\

--memoryTff7b72=1g Tffea00\

--memory-reservationTff7b72=256m Tffea00\

--pids-limitTff7b72=T79c0ff512 Tffea00\

-p T79c0ff127.0.0.1:8000:8000 Tffea00\

-v meshchatx-config:/config Tffea00\

ghcr.io/quad4-software/meshchatx:latest

Ta5d6ff```

Default Compose maps Ta5d6ff`127.0.0.1:8000` on the host to port Ta5d6ff`8000` in the container. Data persists in the Ta5d6ff`meshchatx-config` volume at Ta5d6ff`/config`.

To bind a host directory instead, mount it at Ta5d6ff`/config`. The container runs as UID 1000. The host directory must be writable by that user.

Run only **one** MeshChatX instance per Ta5d6ff`/config` volume. Startup takes an exclusive storage lock so schema migration and runtime do not overlap. For Docker or Coolify, use a single replica on that volume and replace containers in a rolling stop-then-start order instead of two replicas sharing one config path.

Tc9d1d9### Public demo instance (Coolify)

For a read-only mesh showcase on [Tff7b72Coolify](Te6edf3https://coolify.io/docs/knowledge-base/docker/compose), deploy [Ta5d6ff`docker-compose.demo.yml`](../../docker-compose.demo.yml). For a normal (non-demo) Coolify deployment, use [Ta5d6ff`docker-compose.coolify.yml`](../../docker-compose.coolify.yml).

Tff7b72- Ta5d6ff`MESHCHAT_DEMO_MODE=1` blocks outbound mesh actions and almost all API mutations.

Tff7b72- Ta5d6ff`MESHCHAT_AUTH=1` with default showcase password Ta5d6ff`demo` (Ta5d6ff`MESHCHAT_DEMO_AUTH_PASSWORD`).

Tff7b72- Optional Ta5d6ff`MESHCHAT_AUTH_PAGE_HINT` shows custom text on the login page (for example Ta5d6ff`Username: demo` and Ta5d6ff`Password: demo`). Demo compose sets a default hint.

Tff7b72- Ta5d6ff`MESHCHAT_ALTCHA_ENABLED=1` and a strong Ta5d6ff`MESHCHAT_ALTCHA_HMAC_KEY` (required in demo compose via Ta5d6ff`:?`). The UI uses ALTCHA widget v3 with Ta5d6ff`PBKDF2/SHA-256` challenges from Ta5d6ff`/api/v1/auth/altcha/challenge`.

Tff7b72- Assign a domain with container port **8000**, for example Ta5d6ff`https://meshchatx.example.com:8000`.

Tff7b72- Do not set Ta5d6ff`MESHCHAT_AUTH_BYPASS=1` on a public host.

Tc9d1d9## Python wheel

Tff7b721. Download Ta5d6ff`reticulum_meshchatx-*-py3-none-any.whl` from [Tff7b72releases](Te6edf3https://github.com/Quad4-Software/MeshChatX/releases).

Tff7b722. Install with pip, pipx, or uv:

Ta5d6ff```Ta5d6ffbash

pip install reticulum_meshchatx-*.whl

Ta5d6ff```

Tff7b723. Start the server:

Ta5d6ff```Ta5d6ffbash

meshchatx --headless --host T79c0ff127.0.0.1

Ta5d6ff```

The Ta5d6ff`meshchat` command is a compatibility alias for the same entry point.

On hosts where Ta5d6ff`libopus` is installed but Ta5d6ff`libogg` is not, LXST's vendored pyogg can raise Ta5d6ff`NameError: c_int_p` on import. MeshChatX applies a ctypes compatibility fix at startup (the same patch Docker runs after install). Optional telephony audio still needs the usual Opus/Ogg system libraries when you use those codecs.

Tc9d1d9## Linux AppImage and packages

**AppImage**

Ta5d6ff```Ta5d6ffbash

chmod +x ./ReticulumMeshChatX-v*-linux-*.AppImage

./ReticulumMeshChatX-v*-linux-*.AppImage

Ta5d6ff```

**Debian package**

Ta5d6ff```Ta5d6ffbash

sudo dpkg -i reticulum-meshchatx_*_amd64.deb

Ta5d6ff```

Adjust the filename for your architecture.

Tc9d1d9## From source (development)

Ta5d6ff```Ta5d6ffbash

task install

task dev

Ta5d6ff```

Ta5d6ff`task dev` starts the HTTPS backend on Ta5d6ff`127.0.0.1:8000` and Vite on [Tff7b72http://127.0.0.1:5173](Te6edf3http://127.0.0.1:5173). Open that Vite URL. The [Tff7b72Vue DevTools](Te6edf3https://devtools.vuejs.org/) overlay is injected for this serve only. Ta5d6ff`vite build` / Ta5d6ff`task run` never ship it (Ta5d6ff`__VUE_PROD_DEVTOOLS__` is false). Set Ta5d6ff`MESHCHAT_VUE_DEVTOOLS=0` to hide the overlay. Click a component in the inspector to open it in the editor (Ta5d6ff`LAUNCH_EDITOR`, default Ta5d6ff`code`).

Python breakpoints: Ta5d6ff`task debug` is the same stack with [Tff7b72debugpy](Te6edf3https://github.com/microsoft/debugpy) listening on Ta5d6ff`127.0.0.1:5678` (never Ta5d6ff`0.0.0.0`). Run **MeshChatX: Vite + Python** from the debugger, or start Ta5d6ff`task debug` and attach **Backend: Attach debugpy**. Ta5d6ff`task debug:wait` pauses the backend until that attach happens.

A production-like run without HMR:

Ta5d6ff```Ta5d6ffbash

pnpm run build-frontend

uv run python -m meshchatx.meshchat --headless --host T79c0ff127.0.0.1

Ta5d6ff```

Useful task targets include Ta5d6ff`task format`, Ta5d6ff`task lint`, Ta5d6ff`task test`, Ta5d6ff`task test:fe:ui`, and Ta5d6ff`task build`.

Tc9d1d9## First launch

On first run MeshChatX creates a random Reticulum identity if you do not pass one on the command line. The identity file is stored under your configured storage directory.

Open the UI at the host and port you chose. HTTPS is enabled by default with a self-signed certificate unless you pass Ta5d6ff`--no-https` or provide your own PEM files.

Tc9d1d9## Command-line options

Common flags and environment variables:

| Flag | Environment variable | Default | Description |

| ------------------------ | ------------------------------- | -------------- | ----------------------------------------------------------------------------------- |

| Ta5d6ff`--host` | Ta5d6ff`MESHCHAT_HOST` | Ta5d6ff`127.0.0.1` | Bind address |

| Ta5d6ff`--port` | Ta5d6ff`MESHCHAT_PORT` | Ta5d6ff`8000` | HTTP or HTTPS port |

| Ta5d6ff`--no-https` | Ta5d6ff`MESHCHAT_NO_HTTPS` | false | Serve plain HTTP |

| Ta5d6ff`--ssl-cert` | Ta5d6ff`MESHCHAT_SSL_CERT` | auto | TLS certificate path |

| Ta5d6ff`--ssl-key` | Ta5d6ff`MESHCHAT_SSL_KEY` | auto | TLS private key path |

| Ta5d6ff`--headless` | Ta5d6ff`MESHCHAT_HEADLESS` | false | Do not open a browser |

| Ta5d6ff`--auth` | Ta5d6ff`MESHCHAT_AUTH` | false | Require HTTP basic auth for the UI |

| Ta5d6ff`--storage-dir` | Ta5d6ff`MESHCHAT_STORAGE_DIR` | Ta5d6ff`./storage` | Application data directory |

| Ta5d6ff`--reticulum-config-dir` | Ta5d6ff`MESHCHAT_RETICULUM_CONFIG_DIR` | Ta5d6ff`~/.reticulum` | Reticulum configuration |

| Ta5d6ff`--data-dir` | Ta5d6ff`MESHCHAT_DATA_DIR` | none | Portable root (Ta5d6ff`storage` + Ta5d6ff`.reticulum` subdirs when the two paths above are unset) |

| Ta5d6ff`--identity-file` | Ta5d6ff`MESHCHAT_IDENTITY_FILE` | none | Load identity from file |

| Ta5d6ff`--rns-log-level` | Ta5d6ff`MESHCHAT_RNS_LOG_LEVEL` | none | Reticulum log level |

| Ta5d6ff`--auto-recover` | Ta5d6ff`MESHCHAT_AUTO_RECOVER` | false | Attempt SQLite recovery on start |

| Ta5d6ff`--emergency` | | false | Start without database |

| Ta5d6ff`--disable-plugins` | | false | Disable the plugin system |

CLI flags override environment variables when both are set.

Tc9d1d9### Portable installs (removable media, Tails, USB sticks)

MeshChatX already supports relocating all persistent state off the home directory. Use either explicit paths or a single data root:

Ta5d6ff```Ta5d6ffbash

Tffa657export Te6edf3PERSISTTff7b72=Ta5d6ff"/media/amnesia/Persistent/meshchatx"

mkdir -p Ta5d6ff"Te6edf3$PERSISTTa5d6ff"

meshchatx --headless Tffea00\

--data-dirTff7b72=Ta5d6ff"Te6edf3$PERSISTTa5d6ff"

Ta5d6ff```

That creates and uses Ta5d6ff`$PERSIST/storage` for MeshChatX (identities, SQLite, plugins) and Ta5d6ff`$PERSIST/.reticulum` for Reticulum interfaces and transport config. You can set the same layout with environment variables:

Ta5d6ff```Ta5d6ffbash

Tffa657export Te6edf3MESHCHAT_DATA_DIRTff7b72=Ta5d6ff"Te6edf3$PERSISTTa5d6ff"

meshchatx --headless

Ta5d6ff```

Equivalent explicit form (overrides any Ta5d6ff`--data-dir` subpaths when you set these yourself):

Ta5d6ff```Ta5d6ffbash

meshchatx --headless Tffea00\

--storage-dirTff7b72=Ta5d6ff"Te6edf3$PERSISTTa5d6ff/storageTa5d6ff" Tffea00\

--reticulum-config-dirTff7b72=Ta5d6ff"Te6edf3$PERSISTTa5d6ff/.reticulumTa5d6ff"

Ta5d6ff```

The Electron desktop app (AppImage, portable exe, macOS bundle) honors the same Ta5d6ff`--data-dir` / Ta5d6ff`--storage-dir` / Ta5d6ff`--reticulum-config-dir` flags (or the matching Ta5d6ff`MESHCHAT_DATA_DIR` / Ta5d6ff`MESHCHAT_STORAGE_DIR` / Ta5d6ff`MESHCHAT_RETICULUM_CONFIG_DIR` environment variables) on every platform, not just Windows:

Ta5d6ff```Ta5d6ffbash

Tffa657export Te6edf3PERSISTTff7b72=Ta5d6ff"/media/amnesia/Persistent/meshchatx"

./MeshChatX-x86_64.AppImage --data-dirTff7b72=Ta5d6ff"Te6edf3$PERSISTTa5d6ff"

Ta5d6ff```

On Windows portable exe builds, storage and Reticulum config also default next to the Ta5d6ff`.exe` when Ta5d6ff`PORTABLE_EXECUTABLE_DIR` is set (used by the portable target automatically), without needing any flags.

Tc9d1d9## Reticulum manual bundle

The Reticulum HTML manual is fetched from the upstream website **master** branch at build time by default (clearnet ZIP). There is no in-app clearnet refresh. After cloning the repository, or before packaging a release, run:

Ta5d6ff```Ta5d6ffbash

pnpm run build-docs

Ta5d6ff```

CI release builds use the clearnet path. Without a bundled copy the Reticulum tab may show an upload prompt until you build docs or upload a manual ZIP offline.

Tc9d1d9## Advanced: Optional RNS-only installation (pip-rns)

MeshChatX includes optional tooling to pull Ta5d6ff`rns`, Ta5d6ff`lxmf`, Ta5d6ff`lxst`, and the Reticulum manual from markqvist's rngit remotes over the mesh instead of clearnet.

**Note:** Installing Python packages over RNS is slower than PyPI and fits mesh-only hosts with restricted clearnet. PyPI remains the default path for CI and standard development.

| Remote | Purpose |

| ------------------------------------------------------------ | --------------------- |

| Ta5d6ff`rns://7649a50d84610232d1416b41d2896aff/reticulum/reticulum` | RNS package |

| Ta5d6ff`rns://7649a50d84610232d1416b41d2896aff/reticulum/lxmf` | LXMF package |

| Ta5d6ff`rns://7649a50d84610232d1416b41d2896aff/reticulum/lxst` | LXST package |

| Ta5d6ff`rns://7649a50d84610232d1416b41d2896aff/reticulum/website` | Manual / website HTML |

This uses [Tff7b72pip-rns](Te6edf3https://github.com/Quad4-Software/pip-rns) for the Python packages and Ta5d6ff`git` + Ta5d6ff`git-remote-rns` for the docs tree. Default aliases live in Ta5d6ff`scripts/pip-rns/aliases`.

**Bootstrap note:** pip-rns needs a working Reticulum stack to reach the remotes. Install Ta5d6ff`rns` once from PyPI, a wheel, or an existing environment, then use the mesh path for updates.

Ta5d6ff```Ta5d6ffbash

T8b949e# Optional: Install/update rns, lxmf, lxst into the uv environment over RNS

task deps:backend:rns

T8b949e# Optional: Bundle the Reticulum manual from the rngit website remote

task docs:rns

Ta5d6ff```

Equivalent direct commands:

Ta5d6ff```Ta5d6ffbash

bash scripts/pip-rns-deps.sh

python scripts/build/fetch_reticulum_manual.py --force --via-rns

Ta5d6ff```

Set Ta5d6ff`PIP_RNS_CONFIG` to point at another aliases directory if needed. Ta5d6ff`MESHCHATX_RETICULUM_DOCS_URL=rns://...` also works for a custom website remote.

Tc9d1d9## Identity bootstrap

You can supply an identity at startup:

Tff7b72- Ta5d6ff`--identity-file /path/to/identity`

Tff7b72- Ta5d6ff`--identity-base64` or Ta5d6ff`--identity-base32` with the corresponding environment variables

Otherwise MeshChatX generates one and saves it under Ta5d6ff`<storage>/identity`. Additional identities are created from the **Identities** page. Each identity has its own database, LXMF router, and settings while sharing one Reticulum process.

Tc9d1d9## After install

Tff7b721. Add at least one **interface** so Reticulum can reach peers.

Tff7b722. Review **Settings** for display name, theme, language, and LXMF stamp costs.

Tff7b723. Enable **telephone** in settings if you plan to use audio calls.

Tff7b724. Open **Documentation** for MeshChatX guides and the Reticulum manual offline.

Platform-specific notes live under **Platform guides** in this documentation bundle.